Fix engineering-workflow component refinements#128
Fix engineering-workflow component refinements#128Alan-Jowett merged 2 commits intomicrosoft:mainfrom
Conversation
Address all three issues from microsoft#120: 1. Add explicit change-propagation protocol Phases 3-5 to generation templates (generate-spec-changes, generate-implementation-changes): - Step 4: Invariant check - Step 5: Completeness check (flag DROPPED upstream changes) - Step 6: Conflict detection (internal, cross-artifact, upstream) - Renumbered Assemble Patch to Step 7 2. Switch multi-input contract types from YAML lists to single primary type with description documenting secondary inputs: - audit-spec-alignment: type: requirements-patch (was list) - audit-implementation-alignment: type: spec-patch (was list) 3. Switch interactive workflow templates from format: multi-artifact to format: null — multi-artifact requires an upfront Deliverables manifest which conflicts with interactive mode (Phase 1 starts with questions, not artifacts): - engineering-workflow.md - spec-extraction-workflow.md - maintenance-workflow.md - Corresponding manifest entries updated Closes microsoft#120 Co-authored-by: Copilot <[email protected]>
There was a problem hiding this comment.
Pull request overview
Refines the engineering-workflow prompt components to address post-merge cleanup items from #120 by making change-propagation phases explicit, aligning contract typing with pipeline chaining expectations, and removing the conflicting multi-artifact format requirement from interactive workflows.
Changes:
- Added explicit Invariant/Completeness/Conflict phases to the spec + implementation change-generation templates (renumbering Assemble Patch to Step 7).
- Switched multi-input
input_contract.typefields from YAML lists to a single primary type (with secondary inputs described in the contract description). - Set interactive workflow templates to
format: nulland removed theirformatentries frommanifest.yamlto match.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| templates/spec-extraction-workflow.md | Sets format: null for the interactive workflow to avoid multi-artifact output constraints. |
| templates/maintenance-workflow.md | Sets format: null for the interactive workflow to avoid multi-artifact output constraints. |
| templates/engineering-workflow.md | Sets format: null for the interactive workflow to avoid multi-artifact output constraints. |
| templates/generate-spec-changes.md | Adds explicit Steps 4–6 (invariant, completeness, conflict checks) before assembling the patch. |
| templates/generate-implementation-changes.md | Adds explicit Steps 4–6 (invariant, completeness, conflict checks) before assembling the patch. |
| templates/audit-spec-alignment.md | Changes input_contract.type to a single primary type and updates the description to document secondary inputs. |
| templates/audit-implementation-alignment.md | Changes input_contract.type to a single primary type and updates the description to document secondary inputs. |
| manifest.yaml | Removes format: multi-artifact from the affected interactive templates so manifest matches format: null usage. |
Co-authored-by: Copilot <[email protected]>
| taxonomies: | ||
| - specification-drift | ||
| format: multi-artifact | ||
| format: null |
There was a problem hiding this comment.
format is now null, but later instructions still say “Because this template uses the multi-artifact format…” when describing output constraints. With no format component being assembled, that statement is incorrect; adjust the prose to reference the intended constraints directly (or restore multi-artifact if you still want that format enforced).
| input_contract: | ||
| type: [requirements-patch, spec-patch] | ||
| type: requirements-patch | ||
| description: > | ||
| Structured patches for requirements and specifications, plus the | ||
| user's original intent description. | ||
| A structured requirements patch as the primary input, plus the | ||
| user's original intent description and the specification | ||
| patch for cross-referencing. |
There was a problem hiding this comment.
input_contract.type no longer matches the preceding pipeline stage output (generate-spec-changes produces spec-patch), which conflicts with the pipeline contract rule that adjacent stages’ output/input types match. To keep pipeline chaining/validation working, set the primary input_contract.type to spec-patch and mention the requirements patch as a secondary input in the description (similar to how audit-traceability uses validation-plan as the primary type).
| input_contract: | ||
| type: [spec-patch, implementation-patch] | ||
| type: spec-patch | ||
| description: > | ||
| Structured patches for specifications and implementation, to be | ||
| audited for alignment. | ||
| A structured specification patch as the primary input, plus an | ||
| implementation patch to be audited for alignment against it. |
There was a problem hiding this comment.
input_contract.type is set to spec-patch, but in the engineering-workflow pipeline this stage follows generate-implementation-changes (which produces implementation-patch). This breaks the documented contract-chaining rule (adjacent stage output/input types match) and can prevent correct next-stage suggestions/validation. Consider making the primary input_contract.type implementation-patch and documenting the spec-patch as a secondary input in the description (pattern matches audit-traceability).
| taxonomies: | ||
| - specification-drift | ||
| format: multi-artifact | ||
| format: null |
There was a problem hiding this comment.
After switching format to null, the template body still states that the assembled prompt includes only the multi-artifact format (see later in the file around the requirements extraction output instructions). This is now incorrect and can mislead users/agents about what “Output Format” content is present; update that wording (or reintroduce multi-artifact if that’s actually required).
| format: null | |
| format: multi-artifact |
Summary
Addresses all three post-merge cleanup items from #120.
Closes #120
Changes
1. Explicit change-propagation protocol phases (Steps 4-6)
Affected:
generate-spec-changes.md,generate-implementation-changes.mdAdded three new steps before Assemble Patch:
Assemble Patch renumbered to Step 7.
2. Single-type input contracts
Affected:
audit-spec-alignment.md,audit-implementation-alignment.mdChanged
input_contract.typefrom YAML lists to single primary type with description documenting secondary inputs:audit-spec-alignment:type: requirements-patch(was[requirements-patch, spec-patch])audit-implementation-alignment:type: spec-patch(was[spec-patch, implementation-patch])3. format: null for interactive workflows
Affected:
engineering-workflow.md,spec-extraction-workflow.md,maintenance-workflow.mdSwitched from
format: multi-artifacttoformat: null. Themulti-artifactformat requires output to begin with a Deliverables manifest, which conflicts with interactive mode where Phase 1 starts with discovery questions. These templates define their output structure inline.Validation
Both validators pass cleanly.